<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
	<HEAD>
		<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
		<META name="GENERATOR" content="IBM WebSphere Studio">
	</HEAD>
	<BODY>
		<!-- Begin Common Doc (Swaf.Container) -->
		<P>Defines the base support for a generic map like mechanism that uses a class 
			factory for its node types, and includes several implementations of various 
			node types.</P>
		<style> .code {font: 8pt Courier}
	</style>
		<p>
			Rather then store the objects passed in a call to its put method directly in 
			its own simple storage mechanism, the cache map creates an IContainerNode 
			object that stores the client object and manages it.This allows data management 
			strategies to be applied against client data to ease that responsibility from 
			the client code itself.The cache map is a map of IContainerNode objects.The 
			base&nbsp;container package&nbsp;provides a set of IContainerNode 
			implementations that provide for:</p>
		<ul>
			<li>
				Time expiration with various time options.Time can be specified for:
				<ul>
					<li>
					A specific amount of time to pass from when the data was first put into the 
					map.
					<li>
					A specific point in time in the future.
					<li>
						A sliding amount of time that gets reset when a client access the data through 
						a call to the CacheMap.get method.</li>
				</ul>
			<li>
			Basic Java object pooling.A pool of objects can be defined for a specific key 
			in the map.This type of node doesn't support calls to put on the key after the 
			pool is setup, but calling get will retrieve an object out of the pool.Pool 
			options such as min and max number of objects to keep in the pool can be 
			specified.
			<li>
			Read only objects.The object can only be removed, but calls to put will cause 
			an exception to be thrown.
			<li>
			Never expire so that objects put into the CacheMap stay in the map until 
			specifically removed.
			<li>
				Xml Document caching that is capable of time expiring the in memory DOM, but on 
				calls to get that require the DOM to recreate the DOM from the XML source 
				before returning the value.</li>
		</ul>
		<p>The&nbsp;IContainer interface&nbsp;provides an advanced put method over what is 
			defined in the java.util.Map interface that allows a string parameter to be 
			passed that configures the type of&nbsp;node for the item being put into the 
			map.</p>
		<p class="Code">void Put(String key, Object value, String nodeOptions);</p>
		<p>The nodeOptions parameter specifies a node regex pattern (From 
			Resource.PatternRepository class) similar to the IBusinessObject field 
			validation options.An example call such as:</p>
		<p class="Code">myCache.put("deckOfCards", myDeck, "Time expire in 5 hours");</p>
		<p>The nodeOptions in the example will cause the deckOfCards item to be removed 
			from the cache map 5 hours in the future.</p>
		<p>Each implementation of IContainerNode to be used in a container needs to be 
			defined in the "ContainerNode" class factory definition.&nbsp; When calling put 
			with a nodeOptions, it is used as a regexp pattern against the class 
			factory.&nbsp; When a match is made between a configuration pattern and the 
			nodeOptions parameter, the CacheMap creates an instance of the IContainerNode 
			and gives in the valuing being put into the map and the nodeOptions passed in 
			so that the cache node can configure itself.</p>
		<p>Some IContainerNode implementations are designed to work with specific java 
			Class types only.When inserting an object into the CacheMap that uses a 
			nodeOptions pattern that needs a specific class type and the object being 
			inserted doesn't extend or implement that class type, an exception is thrown.</p>
		<h4>Container element&nbsp;naming support</h4>
		<p>The&nbsp;container package&nbsp;implements the framework namespace address 
			mechanism so that calls to get can actually get values within values of the 
			container.&nbsp; For example, if a framework IBusinessObject is put into 
			the&nbsp;container that has a field called firstName, a call such as:</p>
		<p class="Code">name = myCacheMap.get("customer.firstName");</p>
		<p>
			The node associated with the key "customer" is found, and then the 
			IBusinessObject is queried for its "firstName".&nbsp; Any class that implements 
			the IContainerNode&nbsp;should support this level of drill down 
			addressing.&nbsp; Objects that are put into the&nbsp;container that don't 
			support namespace addresses will use a namespace address support object that 
			will use java reflection to continue the address parsing.<o:p></o:p></p>
		<h4>Configuration</h4>
		<p>The cache map hooks into the base configuration to allow configuration of its 
			basic operations.</p>
		<h5>Default node type</h5>
		<p>When a client inserts data into the map without specifying a node option (such 
			as when the client is using the map through the java.util.Map interface), the 
			node type specified in the 
			&lt;CacheMap&gt;&lt;DefaultNode/&gt;&lt;/CacheMap&gt; element of the app config 
			will be used by default.Not having that option defined in the app config is 
			considered an application configuration error.</p>
		<h5>Default node mapping</h5>
		<p>As a defaulting mechanism that overrides the basic "default node type" 
			configuration this configuration option allows a specific object type being 
			inserted into the map to be automatically associated with a particular node 
			type.&lt;CacheMap&gt;&lt;DefaultMapping/&gt;&lt;/CacheMap&gt; elements allow 
			java class types to be mapped to cache node types so that inserting without 
			node options will result in a node type other then the basic "default node 
			type".</p>
		<p>This option shouldn't be over-used as it will affect the performance of putting 
			items into the cache map when not specifying a node type regex.</p>
		<h4>CacheMap Persistance</h4>
		<p>When client code creates a new instance of CacheMap, an optional string 
			identifier can be passed in that will be used to locate a CacheMap node 
			persistence XML file.The CacheMap will use the Node persistence XML to recreate 
			a set of nodes and their configuration.This makes for easy setup of CacheMap 
			objects that can have many pre-populated map entries.</p>
		<p>The CacheMap node persistence XML is simple enough to be hand coded, but can 
			also be created via Java serialization of the CacheMap object.This means that a 
			CacheMap object can be created, populated, and then serialized to an XML 
			document via standard Java serialization, then later recreated via standard 
			serialization or a special constructor that takes a string identifier that is 
			essentially a moniker to the XML file.</p>
	<!-- End Common Doc -->
	</BODY>
</HTML>
